Description

• This PR introduces handler-based Shell architecture for Android, replacing the legacy renderer-based approach (ShellRenderer, ShellFlyoutRenderer, ShellItemRenderer, ShellSectionRenderer) with new handler classes that reuse standard MAUI platform components. The new architecture follows the same patterns used by FlyoutViewHandler, NavigationViewHandler, and TabbedPageManager, achieving the long-standing architectural goal of building Shell from the same building blocks as non-Shell features.

Platform: Android only. iOS/MacCatalyst continue to use legacy ShellRenderer.

Motivation

The legacy Shell renderers on Android are monolithic, tightly coupled, and duplicate functionality that already exists in standard MAUI handlers:

• ShellFlyoutRenderer extends DrawerLayout directly (IS-A relationship) — duplicates FlyoutViewHandler drawer logic
• ShellItemRenderer manages its own BottomNavigationView — duplicates TabbedPageManager tab logic
• ShellSectionRenderer manages its own toolbar, navigation stack, and content tabs — duplicates NavigationViewHandler and TabbedPageManager patterns
• Fragment management, layout inflation, and view hierarchy are all custom per-renderer

The new handler architecture:

• Reuses MauiDrawerLayout — same shared component as FlyoutViewHandler
• Reuses TabbedViewManager — shared tab management for both Shell and TabbedPage
• Uses XML layout inflation — follows established MAUI patterns (navigationlayout.axml, shellitemlayout.axml, shellsectionlayout.axml)
• Maps cleanly to Shell's virtual view hierarchy — Shell → ShellHandler, ShellItem → ShellItemHandler, ShellSection → ShellSectionHandler

Architecture Overview

Handler Hierarchy

Shell (IFlyoutView)
└── ShellHandler : ViewHandler<Shell, MauiDrawerLayout>
    ├── MauiDrawerLayout (shared with FlyoutViewHandler)
    │   ├── navigationlayout.axml (content root)
    │   └── Flyout content (ShellFlyoutTemplatedContentRenderer — reused from legacy)
    │
    └── ShellItem
        └── ShellItemHandler : ElementHandler<ShellItem, ViewPager2>
            ├── shellitemlayout.axml (CoordinatorLayout + ViewPager2)
            ├── BottomNavigationView (via TabbedViewManager)
            ├── Toolbar (shared across all sections — persists on section switch)
            └── ShellSection
                └── ShellSectionHandler : ElementHandler<ShellSection, AView>
                    ├── shellsectionlayout.axml (LinearLayout + ViewPager2)
                    ├── TabLayout (via TabbedViewManager, hidden if single content)
                    └── ShellContent → StackNavigationManager (independent nav stack per content)

Key Design Decisions

New Files

Core Layer (src/Core/)

Controls Layer (src/Controls/)

Modified Files

Handler Registration

Opt-In Infrastructure

Shared Component Extraction

Core Interfaces

Compatibility Layer Fixes

Virtual View Changes

PublicAPI

Updated PublicAPI.Unshipped.txt files across all TFMs for new public types and interface members:

• MauiDrawerLayout, MauiDrawerLayout.FlyoutLayoutMode
• ITab, ITabbedView expanded members
• TabBarPlacement enum
• ShellHandler, ShellItemHandler, ShellSectionHandler handler types

Shared Infrastructure Summary

The PR achieves the core architectural goal — Shell now uses the same building blocks as non-Shell features:

Fragment Architecture

Shell handlers use wrapper fragments to integrate with Android's FragmentManager:

FragmentManager (Activity)
└── ShellItemWrapperFragment (committed by ShellHandler)
    ├── Inflates shellitemlayout.axml
    ├── Sets up ShellItemHandler with real ViewPager2 from XML
    │
    └── ChildFragmentManager
        └── ShellSectionWrapperFragment (via ViewPager2 FragmentStateAdapter)
            ├── Inflates shellsectionlayout.axml
            ├── Sets up ShellSectionHandler with real ViewPager2 from XML
            │
            └── ChildFragmentManager
                └── ShellContentNavigationFragment (via ViewPager2 FragmentStateAdapter)
                    ├── Uses StackNavigationManager for navigation
                    └── Hosts actual page content

All fragment subclasses have default constructors for Android's Fragment.instantiate() reflection requirement, with null guards in OnCreateView() for graceful restoration handling.

Opt-In Mechanism

The Shell on Android now supports both the legacy renderer-based approach and the new handler-based approach, controlled by the UseAndroidShellHandlers MSBuild property (following the same pattern as UseMaterial3).

How to Enable

<!-- In .csproj or Directory.Build.props -->
<PropertyGroup>
  <UseAndroidShellHandlers>true</UseAndroidShellHandlers>
</PropertyGroup>

Or via command line: dotnet build -p:UseAndroidShellHandlers=true

Flow

UseAndroidShellHandlers MSBuild property → build targets → AppHostBuilderExtensions conditionally registers handlers or legacy ShellRenderer.

What Changes When Enabled

Note: iOS/MacCatalyst are not affected — they always use ShellRenderer regardless of this setting.

Testing

• UseAndroidShellHandlers=true is set in the following test/sample projects for CI validation:
  • Controls.TestCases.HostApp.csproj — UI tests
  • Controls.DeviceTests.csproj — Device tests
• No new device tests required — the handler produces identical visual output to the renderer
• Handler is enabled in this branch to validate against the full UI test suite

Issues Fixed

Fixes #32985